What is a Dialog Event?

Description

Every action that the user performs while interacting with a dialog can potentially generate an event. By default, the only event that is generated is when the users clicks on a button. However, you can specify that your dialog should generate other events, such as when the value in a control changes, or when a control gets or loses focus.

When an event is generated, the name of the event just generated is stored in a special Alpha Anywhere system variable, a_dlg_button. The syntax of the UI_DLG_BOX() command is:

ui_dlg_box(title, dialog_format [, event_handling_code ])

Up until now, we have not used the optional event_handling_code parameter. This is where you specify the Xbasic code that handles the events generated by the dialog box. Consider the following trivial dialog box:

Result = Ui_dlg_box("Title",<<%dlg%
Hello World;
<*15&OK> <&Cancel>
%dlg%)

When the dialog is displayed, clicking on either the OK or the Cancel button will close the dialog. This is because there is no event_handling_code to process the event when the user clicks OK, or Cancel, and so the dialog simply closes and stores the name of the last event in the result variable. In this case, if the user clicked the OK button, result will contain ' &OK ', and if the user clicked the 'Cancel' button, result will contain ' &Cancel '.

By default, the name of the event generated by clicking a button is simply the button text. So, in the example, above, the name of the event generated by clicking the OK button is ' &OK '. Alternatively, you can explicitly specify the name of the event generated when a button is clicked by specifying the event name after the '!' character. For example, <*15&OK!ok_button>, generates an event called ok_button when the button is pressed.

<<%code% ... %code%

The <<%code% ... %code% section is optional. If present, it immediately follows the <<%dlg% ... %dlg%, separated by a comma. The following code defines the framework for a dialog box with a code handler.

Result = ui_dlg_box("Title",<<%dlg%
...
%dlg%,<<%code%
...
%code%)

The code handler script contains segments in the following format. When dealing with a modal dialog ( UI_DLG_BOX()), setting the value of a_dlg_button to NULL keeps the dialog box open. Conversely, allowing a_dlg_button to retain a value causes the dialog box to close.

<<%code%
if (a_dlg_button = "event_name") then
    a_dlg_button = ""
    ... do something
end if
if (a_dlg_button = "event_name") then
    ... end the dialog
end if
%code%)

Say, instead of closing the dialog when the user clicked the "OK" button you wanted to display another dialog box. Here is how you could do it:

Result = Ui_dlg_box("Title",<<%dlg%
Hello World;
<*15&OK> <&Cancel>
%dlg%,<<%code%
if a_dlg_button = "&OK" then
    ui_msg_box("Notice","User clicked the OK button.")
end if
%code%)

Now, when the dialog is displayed, if the user clicks the OK button, this message box is displayed and then when this message box is dismissed, the dialog closes. As a further refinement, when the user dismisses the message box, say that you would like the dialog to stay open, and when the user clicks the Cancel button, you would like a message box to prompt, 'Are you sure?'.

Limitations

Desktop applications only